前言

在本章節中，主要整理一些ClickHouse資料庫伺服器在建置的時候出現的錯誤與問題。

ClickHouse資料庫安裝的問題

無法使用apt-get指令執行ClickHouse資料庫相關套件的安裝，應該要檢查下列的事項：

• 檢查網路防火牆設定，是否連到網際網路或是連到與ClickHouse有關的連結網址有被阻擋。

• 如果仍然無法解決上述的問題，則可以手動下載DEB套件並使用sudo dpkg -i指令進行手動的安裝，相關的連結網址如下：

  • https://packages.clickhouse.com/deb/pool/main/c/clickhouse

• 需要有這三個套件：

  • clickhouse-client
  • clickhouse-common-static
  • clickhouse-server

無法連線到ClickHouse資料庫伺服器

可能的問題如下：

• 該資料庫伺服器沒有啟動。
• 不預期的錯誤或是錯誤的設定參數設定。

可以使用下列的指令進行ClickHouse資料庫服務目前的狀態：

sudo service clickhouse-server status
# 或是
sudo systemctl status clickhouse-server.service

如果使用上述的狀態發現ClickHouse資料庫服務沒有啟動的話，則可以使用下列指令進行啟動：

sudo service clickhouse-server start
# 或是
sudo systemctl start clickhouse-server.service

同時我們也可以檢查記錄，預設資料庫的記錄會放在/var/log/clickhouse-server/clickhouse-server.log之路徑檔案中。

如果伺服器啟動成功的話， 我們應該會看到下列的設定：

• <Information> Application: starting up. — 代表資料庫伺服器已經成功啟動了。
• <Information> Application: Ready for connections. — 表示資料庫伺服器已經正在運行並準備好處理客戶端的連線了。

如果找到記錄中有錯誤，則是以<Error>為開頭的，相關的錯誤記錄訊息如下：

2019.01.11 15:23:25.549505 [ 45 ] {} <Error> ExternalDictionaries: Failed reloading 'event2id' external dictionary: Poco::Exception. Code: 1000, e.code() = 111, e.displayText() = Connection refused, e.what() = Connection refused

同時我們也可以透過下列指令來查看system.d的記錄：

sudo journalctl -u clickhouse-server

各式參數設定問題

如果是以Docker映像檔啟動ClickHouse資料庫並啟動IPv6網路的話，則需要確認是否有設定network=host。

若是存取端點設定問題，則需要檢查伺服器端的設定中的listen_host與tcp_port之設定是否正確。

要注意的是，預設ClickHouse伺服器只允許本地端主機進行連線。

若是有關於HTTP協定的設定，則需要檢查伺服器端有關於HTTP API等相關的設定是否正確。

若是有關於安全連線的設定，則需要檢查伺服器端有關於tcp_port_secure、SSL憑證以及其他關於使用客戶端指令進行安全連線設定的參數設定。
舉例來說，在使用clickhouse-client指令並搭配--secure或是適當的設定檔進行SSL憑證驗證的安全連線。

若是有關於使用者的設定，我們可能使用了錯誤的使用者名稱、密碼或是在設定SSL安全連線時設定錯誤的憑證與私鑰檔案路徑。

無法處理SQL查詢問題

若連上資料庫後無法執行SQL查詢，像是下面使用了curl指令透過HTTP介面連線進行查詢所輸出的錯誤訊息：

$ curl 'http://localhost:8123/' --data-binary "SELECT a"
Code: 47, e.displayText() = DB::Exception: Unknown identifier: a. Note that there are no tables (FROM clause) in your query, context: required_names: 'a' source_tables: table_aliases: private_aliases: column_aliases: public_columns: 'a' masked_columns: array_join_columns: source_columns: , e.what() = DB::Exception

我們可以改用clickhouse-client並搭配--stacktrace參數找出連線後無法執行的問題，相關執該指令所輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ clickhouse-client --stacktrace
ClickHouse client version 22.8.4.7 (official build).
Connecting to localhost:9000 as user default.

If you have installed ClickHouse and forgot password you can reset it in the configuration file.
The password for default user is typically located at /etc/clickhouse-server/users.d/default-password.xml
and deleting this file will reset the password.
See also /etc/clickhouse-server/users.xml on the server where ClickHouse is installed.

Code: 516. DB::Exception: Received from localhost:9000. DB::Exception: default: Authentication failed: password is incorrect or there is no user with such name. Stack trace:

0. DB::Exception::Exception(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&, int, bool) in /usr/bin/clickhouse
1. DB::AccessControl::authenticate(DB::Credentials const&, Poco::Net::IPAddress const&) const in /usr/bin/clickhouse
2. DB::Session::authenticate(DB::Credentials const&, Poco::Net::SocketAddress const&) in /usr/bin/clickhouse
3. DB::TCPHandler::receiveHello() in /usr/bin/clickhouse
4. DB::TCPHandler::runImpl() in /usr/bin/clickhouse
5. DB::TCPHandler::run() in /usr/bin/clickhouse
6. Poco::Net::TCPServerConnection::start() in /usr/bin/clickhouse
7. Poco::Net::TCPServerDispatcher::run() in /usr/bin/clickhouse
8. Poco::PooledThread::run() in /usr/bin/clickhouse
9. Poco::ThreadImpl::runnableEntry(void*) in /usr/bin/clickhouse
10. start_thread in /lib/x86_64-linux-gnu/libpthread-2.27.so
11. clone in /lib/x86_64-linux-gnu/libc-2.27.so
. (AUTHENTICATION_FAILED)

從上述的指令執行後所輸出的訊息可以知道，有關於密碼驗證有問題。

如果每次連線的時候都無法執行查詢，則我們需要檢查啟動伺服器的記錄找出錯誤的訊息。

處理查詢效率問題

如果我們發現ClickHouse資料庫在處理SQL語句很慢的時候，我們應該要檢查該伺服器是不是有其他資源占用的情況，如網路、CPU、記憶體等硬體資源。

我們也可以使用clickhouse-benchmark工具來評估查詢語句，用這工具會顯示每秒處理了多少查詢語句、每秒處理多少資料筆數以及處理語句花了多久的時間。

clickhouse-benchmark用法

下列是clickhouse-benchmark指令的用法：

$ clickhouse-benchmark --query ["single query"] [keys]

或是也可以參考下列的用法：

$ echo "single query" | clickhouse-benchmark [keys]

或是使用下列的用法：

$ clickhouse-benchmark [keys] <<< "single query"

如果我們要一次執行多行的語句，則可以先建立一個SQL檔案，並使用下列的指令進行SQL語句的評估：

clickhouse-benchmark [keys] < queries_file;

上述的[keys]則指的是參數，可以指定的參數如下：

• --query=QUERY — 指定要執行的查詢，如果這個參數沒有指定的話，則clickhouse-benchmark將會從標準輸入（stdin）管線讀取查詢語句。
• -c N或是長參數--concurrency=N — 設定讓clickhouse-benchmark模擬有多少個數量同時併發去執行指定的SQL語句，預設值為：1。
• -d N或是長參數--delay=N — 每次輸出執行報告的間隔時間，若關閉報告則設定0，預設值為：1。
• -h HOST或是長參數--host=HOST — 指定伺服器的主機，預設值為：localhost。
• -p N或是長參數--port=N — 指定伺服器的埠號，預設值為：9000。
• -i N或是長參數--iterations=N — 總共查詢的數量，預設值為：0，將為一直執行查詢。
• -r或是長參數--randomize — 如果指定多個查詢語句時，會以亂數的方式隨機順序執行設定的多個查詢語句。
• -s或是長參數--secure — 使用TLS方式進行資料庫的連線。
• -t N或是長參數--timelimit=N — 設定逾時時間，單位為秒，當逾時時間到了時候，clickhouse-benchmark則會停止傳送查詢，預設值為：0；即於逾時時間設定為關閉的。
• --confidence=N — T-test檢定，的等級可能設定的值為：0 (80%)、1 (90%)、2 (95%)、3 (98%)、4 (99%)與5 (99.5%)。預設值為：5
  • clickhouse-benchmark工具執行了兩個樣本的學生T檢定來決定是否這兩個樣本在選擇的信賴區間中是否是不同的。
• --cumulative — 輸出累積的資料，而不是一個間隔的資料。
• --database=DATABASE_NAME — 指定ClickHouse資料庫名稱，預設值為：default。
• --json=FILEPATH — 使用JSON當作格式輸出，當此參數有設定時，clickhouse-benchmark工具將會輸出以JSON為格式的指定檔案的報告。
• --user=USERNAME — ClickHouse資料庫使用者名稱，預設值為：default。
• --password=PASSWORD — ClickHouse資料庫使用者名稱，預設值為：空字串。
• --stacktrace — 輸出執行堆疊訊息，當這個參數設定時候，clickhouse-bencmark工具將輸出堆疊與可追蹤的例外訊息。
• --stage=WORD — 在伺服器上處理查詢的狀態，ClickHouse資料庫會在指定特殊的狀態時候停止處理語句並回應訊息出來。
  • 可能設定的值為：complete、fetch_columns與with_mergeable_state。預設值為：complete。
• --help — 輸出該工具幫助的訊息。

若要執行查詢語句時需要做設定（settings），則可以使用--<session setting name>= SETTING_VALUE的參數設定達成。

帶入設定參數範例像是：--max_memory_usage=1048576。

下列是執行clickhouse-benchmark工具指令後的輸出訊息：

echo "SELECT 1" | clickhouse-benchmark --password password -i 10 --cumulative
Loaded 1 queries.

Queries executed: 10.

localhost:9000, queries 10, QPS: 1258.224, RPS: 1258.224, MiB/s: 0.001, result RPS: 1258.224, result MiB/s: 0.001.

0.000%          0.001 sec.
10.000%         0.001 sec.
20.000%         0.001 sec.
30.000%         0.001 sec.
40.000%         0.001 sec.
50.000%         0.001 sec.
60.000%         0.001 sec.
70.000%         0.001 sec.
80.000%         0.001 sec.
90.000%         0.001 sec.
95.000%         0.001 sec.
99.000%         0.001 sec.
99.900%         0.001 sec.
99.990%         0.001 sec.

在上述輸出的報告訊息中，我們可以知道幾件事情：

• 在查詢語句執行了多少次。
• 狀態訊息依序包含了：
  • ClickHouse資料庫伺服器的存取端點位址，以上面為例的話，即localhost:9000。
  • 處理了多少查詢的數量。
  • QPS，有多少的的查詢語句每秒在資料庫伺服器進行查詢，即每秒的查詢速率。
  • RPS，有多少筆數在每秒中從伺服器中讀取出來。
  • MiB/s， mebibytes per second，即伺服器每秒讀取出資料的速率是多少。
  • result RPS，有多少筆數在伺服器中每秒放到結果中的速率是多少。
  • result MiB/s，有多少的mebibytes資料在伺服器中每秒放到結果中的速率是多少。
  • 語句執行的時間百分比。

以下是一個使用clickhouse-benchmark的指令範例：

echo "SELECT * FROM system.numbers LIMIT 10000000 OFFSET 10000000" | clickhouse-benchmark -i 10 --password password

執行上述指令所輸出的訊息如下：

peter@ubuntu-s-4vcpu-8gb-amd-sgp1-01:~$ echo "SELECT * FROM system.numbers LIMIT 10000000 OFFSET 10000000" | clickhouse-benchmark -i 10 --password password
Loaded 1 queries.

Queries executed: 5.

localhost:9000, queries 5, QPS: 4.917, RPS: 98556952.837, MiB/s: 751.930, result RPS: 49169001.636, result MiB/s: 375.130.

0.000%          0.182 sec.
10.000%         0.182 sec.
20.000%         0.190 sec.
30.000%         0.190 sec.
40.000%         0.194 sec.
50.000%         0.194 sec.
60.000%         0.194 sec.
70.000%         0.203 sec.
80.000%         0.203 sec.
90.000%         0.248 sec.
95.000%         0.248 sec.
99.000%         0.248 sec.
99.900%         0.248 sec.
99.990%         0.248 sec.



Queries executed: 10.

localhost:9000, queries 10, QPS: 4.883, RPS: 97870199.029, MiB/s: 746.690, result RPS: 48826387.563, result MiB/s: 372.516.

0.000%          0.182 sec.
10.000%         0.187 sec.
20.000%         0.190 sec.
30.000%         0.194 sec.
40.000%         0.200 sec.
50.000%         0.202 sec.
60.000%         0.202 sec.
70.000%         0.203 sec.
80.000%         0.207 sec.
90.000%         0.234 sec.
95.000%         0.248 sec.
99.000%         0.248 sec.
99.900%         0.248 sec.
99.990%         0.248 sec.

結論

在章節中，我們展示了幾種常見的ClickHouse資料庫在安裝、設定與建置的時候常遇到的錯誤情形以及解決的方法，並示範了如何使用clickhouse-benchmark進行查詢語句的執行時間評估。

參考資料

• https://clickhouse.com/docs/en/operations/troubleshooting
• https://clickhouse.com/docs/en/operations/utilities/clickhouse-benchmark